QuickDraw 3D™ 1.5.0 Win32 Platform Preliminary SDK 

Release Notes - December 19, 1996

This preliminary SDK release includes optimized and debug builds of QuickDraw 3D 1.5.0 for Win32.  

Welcome to QuickDraw 3D!  

QuickDraw 3D is a platform independent 3D graphics library developed by Apple Computer.  Enclosed, you will find the 1.5.0 release of QuickDraw 3D for Win32. Note: QuickDraw 3D 1.5.0 for Win32 is equivalent to 1.5.0 on Mac OS.

QuickDraw 3D goes beyond providing 3D graphics, it provides an integrated solution both for the end user and for developers.  QuickDraw 3D encompasses a standard file format (3DMF), acceleration layer, input architecture, high level geometries, and extensibility.

QuickDraw 3D is a library for PowerPC™ based computers running the MacOS and Pentium™ and Pentium Pro™ based computers running Windows 95™ or Windows NT™ 3.51 and 4.0.  The API is in C, with support development using C++.  QuickDraw 3D allows for immediate mode and retained rendering.  The API is object based and provides a large number of geometry types.  The file format accommodates both text and binary modes, with encoding for endianess so that files can be transported to other platforms and across the Internet. 3DMF parser code for several different platforms is available from our Web page at http://quickdraw3d.apple.com.

QuickDraw 3D for Win32 System Requirements
•	Pentium or Pentium Pro processor
•	Windows 95 or Windows NT (3.51 or 4.0)
•	A video board providing 256 color (8-bit) at 640x480 resolution. High Color (16-bit) or True Color (24-bit or 32-bit) video highly recommended.

Development System Requirements
•	Microsoft Visual C++ 4.2
•	MSVCRTD.DLL - the debug version of C runtime DLL which is included with Visual C++ 4.2.

Using this QuickDraw 3D Win32 Preliminary SDK
There are two different builds of QuickDraw 3D for Win32. An optimized build and a debug build. These are located in the Retail and Debug directories respectively. QuickDraw 3D installer installs the Retail version in your system directory.

•	Make sure you clear out any pre-release or old versions of QuickDraw 3D including QD3D.DLL, QD3D_D.DLL, RAVE.DLL, RAVE_D.DLL, QD3D_IR.Q3X, QD3D_IR_D.Q3X, QD3D_IR2.Q3X, and QD3D_IR2_D.Q3X, 3DViewer.DLL, 3DViewer_D.DLL. (You can determine the version of each of these components by examining the “Version- Properties” panel in the Explorer or FileManager. The release build of QuickDraw 3D is “1.5.0.23”)
•	Install the retail version of QuickDraw 3D onto your system. You should run the QuickDraw 3D installer since this will make sure all registry entries are correctly updated. To install QuickDraw 3D run Setup.exe in Redist\QD3D_15 folder
•	Set you Lib and Include paths to reference the QuickDraw 3D Lib and Interfaces directories respectively. (Under Visual C++ this can be done from the Tools|Options|Directories dialog panel.) 
•	Set your system's Path to reference the QuickDraw 3D SDK’s Debug directory where the QuickDraw 3D Debugging DLLs are located. That way debug builds (linked with QD3D_D.LIB or Q3Viewer_D.LIB) of your code can find the appropriate DLLs.
Note: QuickDraw 3D loads plug-ins such as the Interactive Renderer from the same directory as the QuickDraw 3D library so it is important that you have QD3D_IR2.q3x in the same directory as QD3D.dll or QD3D_IR2_D.q3x in the same directory as QD3D_D.dll. The QuickDraw 3D installer copies the optimized DLLs to your Windows\System folder (Win95) or Windows\System32 directory (NT). You should not put the debug DLLs in your system directory because the debug plug-ins (e.g. QD3D_IR2_D.q3x) will get loaded by the optimized library. 

Lib, Include and Path can be also be set using environment variables (in Autoexec.bat on Win95 or in the System control panel on NT).
example: 
   Set LIB = %LIB%;c:\QD3DSDK\LIB
   Set INCLUDE = %INCLUDE%;c:\QD3DSDK\Interfaces
   Set PATH = %Path%;c:\QD3DSDK\LIB

Feature Differences for Win32 Version of QuickDraw 3D
•	Win32 DC, DD Surface and  Pixmap Draw Contexts
QuickDraw 3D for Win32 supports three different draw context types: Win32 DC draw context, DirectDraw™ surface draw context, and Pixmap draw context. The Win32 DC draw context manages double-buffering, rendering and blitting to the screen. When using the DD Surface or Pixmap draw contexts your application is responsible for creating a back-buffer and blitting or flipping the rendered image from the draw context to the screen. See "Implementing Double Buffering Using Pixmap Draw Context and GDI" below.

•	The QuickDraw 3D Pointing Device Manager not supported
The QuickDraw 3D Pointing Device Manager API is not supported in the Win32 version of QuickDraw 3D.

•	The QuickDraw 3D Viewer Controller
QuickDraw 3D for Win32 includes an updated version of the QuickDraw 3D Viewer Controller. The Win32 Viewer Controller API is similar to but different from the MacOS 3D Viewer Controller API. The enclosed file “Win32 3D Viewer ERS” covers the details of the Win32 Viewer Controller API and its use.

•	Win32 Storage
For IO QuickDraw 3D for Win32 supports an additional native storage class -- Win32 Handle Storage. That gives the developer the choice of using the cross-platform, standard-C-library-based Unix Storage, Unix Path Storage, Memory Storage or Memory Buffer Storage or using the Windows specific Win32 Handle Storage. The sample program “Win32Sample” demonstrates basic use of several of these storage classes.

Implementing Double Buffering Using Pixmap Draw Context and GDI
QuickDraw 3D applications using this developer release may use the Win32 DC based draw context or use the generic pixmap draw context. The DirectDraw surface based draw context will be fully supported in a future developer release.

The basic method for managing a pixmap draw context is demonstrated in the NewPixmapDrawContext routine of the enclosed Win32 Sample application project (in the file Do_PixmapDrawContext.c).  It consists of two main steps: Creating a new draw context for a view and rendering.

Creating a draw context for a view:
•	Create a memory device context compatible with the view window's DC and store a reference to it.
	hdc = GetDC(theDocument->fWindow);
	theDocument->fMemoryDC = CreateCompatibleDC(hdc);

•	Create an 16 or 32 bit device independent bitmap (DIB) and select it into the memory device context.
	bitmapInfo.bmiHeader.biSize = sizeof(BITMAPINFOHEADER);	
	bitmapInfo.bmiHeader.biWidth = theDocument->fWidth;	
	bitmapInfo.bmiHeader.biHeight = -theDocument->fHeight; 
// note: negative for top-down DIB	
	bitmapInfo.bmiHeader.biPlanes = 1;
	if ( GetDeviceCaps(hdc, BITSPIXEL) == 32 )
		bitmapInfo.bmiHeader.biBitCount = 32;
	else
		bitmapInfo.bmiHeader.biBitCount = 16;	
	bitmapInfo.bmiHeader.biCompression = BI_RGB;	
	bitmapInfo.bmiHeader.biSizeImage = 0;	
	bitmapInfo.bmiHeader.biXPelsPerMeter = 0;	
	bitmapInfo.bmiHeader.biYPelsPerMeter = 0;	
	bitmapInfo.bmiHeader.biClrUsed = 0;	
	bitmapInfo.bmiHeader.biClrImportant = 0;	
	theDocument->fBitmap = CreateDIBSection(hdc, &bitmapInfo, DIB_RGB_COLORS,	
		&theDocument->fBitStorage, NULL, 0);	
	SelectObject(theDocument->fMemoryDC, theDocument->fBitmap);

•	Create a new pixmap draw context which is parametrized to match the DIB. Set the pixmap draw context's image data pointer to the DIB's bitmap data. The draw context's doubleBufferState flag should be false.
	myDrawContextData.clearImageMethod = kQ3ClearMethodWithColor;
	myDrawContextData.clearImageColor = ClearColor;
	myDrawContextData.paneState = kQ3False;
	myDrawContextData.maskState = kQ3False;
	myDrawContextData.doubleBufferState = kQ3False; 
// the app is doing the double buffering
		/* create a TQ3Pixmap */
	aPixmap.width = theDocument->fWidth;
	aPixmap.height = theDocument->fHeight;
	aPixmap.image = theDocument->fBitStorage;  
//fBitStorage is bitmap data from the DIB
	if (bitmapInfo.bmiHeader.biBitCount == 32)
	{
		aPixmap.rowBytes = aPixmap.width * 4;
		aPixmap.pixelSize = 32;
		aPixmap.pixelType = kQ3PixelTypeRGB32;
	}
	else
	{
		aPixmap.rowBytes = (aPixmap.width * 
			(bitmapInfo.bmiHeader.biBitCount/8));
		aPixmap.rowBytes = (aPixmap.rowBytes + 3) & ~3L; 
// make it long aligned
		aPixmap.pixelSize = 16;
		aPixmap.pixelType = kQ3PixelTypeRGB16;
	}
	aPixmap.bitOrder = kQ3EndianBig;   
/* refers to sub-byte pixel packing order - not applicable */
	aPixmap.byteOrder = kQ3EndianLittle;  
/* must match platform - Win32/x86 is little endian */
		/* set up the pixmap draw context */
	myPixmapDrawContextData.pixmap = aPixmap;
	myPixmapDrawContextData.drawContextData = myDrawContextData;
	myDrawContext = Q3PixmapDrawContext_New(&myPixmapDrawContextData);

•	Set the pixmap draw context as the draw context for the view and dispose of the draw context.
	Q3View_SetDrawContext(myView, myDrawContext);
	Q3Object_Dispose( myDrawContext );

•	Be sure to set the renderer associated with your view to use double buffer bypass. (Remember your application is performing the double buffering).
	myRenderer = Q3Renderer_NewFromType(kQ3RendererTypeInteractive;
	Q3View_SetRenderer(myView, myRenderer;
	Q3InteractiveRenderer_SetDoubleBufferBypass( myRenderer, kQ3True);
	Q3InteractiveRenderer_SetPreferences(myRenderer, kQAVendor_BestChoice, 0);

Rendering (typically in response to WM_PAINT)
•	Do your rendering loop.
	hdc = GetDC(theDocument->fWindow);
	Q3View_StartRendering(theDocument->fView );	
	do {	
		Q3Shader_Submit( theDocument->fIllumination, theDocument->fView );	
		Q3Style_Submit( theDocument->fInterpolation, theDocument->fView );	
		Q3Style_Submit( theDocument->fBackFacing, theDocument->fView );	
		Q3Style_Submit( theDocument->fFillStyle, theDocument->fView );	
		Q3MatrixTransform_Submit( &theDocument->fRotation, 
theDocument->fView );	
		Q3DisplayGroup_Submit( theDocument->fModel, theDocument->fView );	
	} while ( Q3View_EndRendering(theDocument->fView) ==
kQ3ViewStatusRetraverse );	

•	Copy the data from the memory DC to the window using BitBlt.
	BitBlt(hdc, 0, 0, theDocument->fWidth, theDocument->fHeight,	
			theDocument->fMemoryDC, 0, 0, SRCCOPY);					
	ReleaseDC(theDocument->fWindow, hdc);				

Using the Win32DC Draw Context
The new Win32DCDrawContext will automatically manage double-buffering for you. This QuickDraw 3D draw context takes a Win32 GDI DC when created. The DC must be an "owned" DC (ie with the class style CS_OWNDC). QuickDraw 3D will then manage clearing, rasterizing and blitting to that DC.  The basic method for managing a Win32 DC draw context is demonstrated in the NewWin32DCDrawContext routine of the enclosed Win32 Sample application project (in the file Do_Win32DCDrawContext.c).  

Using QuickDraw 3D for Win32 with MFC.
If you intend to use the QuickDraw 3D Win32 DC Draw Context in conjuction with the MFC class library you will need to do a small amount of additional setup because of the Win32 DC Draw Context's requirement of an "owned" DC. The window classes used by  MFC's CWnd and CView C++ classes do not have the CS_OWNDC style by default. You will need to register your own window class for use by MFC if you wish to render directly to a CView based window. The basic process is as follows.

1.	First you need to register a new window class for use by MFC. This can be done during applicaiton initialization. (e.g. in response to CWinApp::InitInstance().)
BOOL QD3DApp::InitInstance()
{
	WNDCLASS wndcls;
	...
	memset(&wndcls, 0, sizeof(WNDCLASS));
	wndcls.style = CS_DBLCLKS | CS_HREDRAW | CS_VREDRAW | CS_OWNDC;
    	wndcls.lpfnWndProc = ::DefWindowProc;
    	wndcls.cbClsExtra = 0;
    	wndcls.cbWndExtra = 0;
    	wndcls.hInstance = AfxGetInstanceHandle();
    	wndcls.hIcon = LoadIcon(IDR_MAINFRAME);
                     // or load a different icon
    	wndcls.hCursor = LoadCursor( IDC_ARROW );
    	wndcls.hbrBackground = (HBRUSH) (COLOR_WINDOW + 1);
    	wndcls.lpszMenuName = NULL;
    	wndcls.lpszClassName = "QuickDraw3DWindow";

    	if( !AfxRegisterClass( &wndcls ))
	{
		TRACE("Window class QuickDraw3DWindow not registered.\n");
		return FALSE;
	}
}

2.	Then in response to PreCreateWindow for your CView derived class insert your new window class's name into the CREATESTRUCT.
BOOL CQD3DView::PreCreateWindow(CREATESTRUCT& cs)
{
	// use our window class
	//
	cs.lpszClass = "QuickDraw3DWindow";
	return CView::PreCreateWindow(cs);
}

See MFC Technical Note: "TN001: Window Class Registration" (Part of Visual C++ Books Online) and Article Q140596 "MFC 4.0 No Longer Pre-Registers Window Classes"

(Cognicon Inc. has published a QuickDraw 3D sample program that uses MFC which you can download and examine. It is available from http://www.cognicon.com/qd3d.htm.)

Library Linking Issues
This preliminary SDK includes debugging and optimized versions of the QuickDraw 3D DLLs. The debugging library requires MSVCRTD.DLL - the debug version of the Visual C++ 4.2 C-runtime library DLL. 

About QuickDraw 3D for Win32's MSVC shared runtime library dependency.
QuickDraw 3D has dependencies on the ANSI C-runtime library.  In fact some QuickDraw 3D APIs pass C-runtime library data structures as parameters (e.g. Q3UnixStorage_New()).  In order for these APIs to work properly the Win32 version of QuickDraw 3D is linked with the DLL version of the C-runtime library. 

The release (optimized) build of QuickDraw 3D requires and is distributed with the non-debug, multithreaded DLL version of Microsoft's Visual C++ 4.2 C-runtime library (MSVCRT.DLL). Unfortunately we are not allowed to distribute the debug build of the MSVC C-runtime library DLL (MSVCRTD.DLL).  You must have a license to Microsoft Visual C++ Professional Edition Version 4.2 to obtain the debug DLL. 

See also: Microsoft Knowledge Base Article Q94248 "Using the C Run-Time" and Visual C++ User's Guide - (Setting Compiler Options:Code Generation) "Use Run-Time Libarary".

What's In This Release?
In the Debug folder (the debug version of QuickDraw 3D 1.5.0)
 QD3D_D.DLL - the debug version of the QuickDraw 3D 1.5 core library,
        dependencies: MSVCRTD.DLL, QD3D_IR2_D.q3x, RAVE_D.DLL

 QD3D_IR2_D.q3x 
- the debug build of the QuickDraw 3D Interactive Renderer plug-in version 1.5
        dependencies: MSVCRTD.DLL, RAVE_D.DLL

 RAVE_D.DLL - the debug build of QuickDraw 3D Accelleration library version 1.5
        dependencies: MSVCRTD.DLL
 
 3DViewer_D.DLL 
- debug build of the 3D Viewer for Windows
        dependencies: QD3D_D.DLL, MSVCRTD.DLL, RAVE_D.DLL, QD3D_IR2_D.q3x

 QuickDraw 3D Viewer (debug).exe 
- the debug build of QuickDraw 3D Viewer application.
        dependencies: 3DViewer_D.DLL, QD3D_D.DLL, MSVCRTD.DLL, RAVE_D.DLL, QD3D_IR2_D.q3x

In the Retail folder (the optimized release version of QuickDraw 3D). 
The QuickDraw 3D Installer will put these libraries into your system directory (typically \Windows\System on Windows 95 and \Windows\System32 on Windows NT).
 QD3D.DLL - the optimized release version of the QuickDraw 3D 1.5 core library,
        dependencies: MSVCRT.DLL, RAVE.DLL, QD3D_IR2.q3x

 MSVCRT.DLL - the release C-Runtime library DLL (from Visual C++ 4.2)

 QD3D_IR2.q3x - the optimized release build of QuickDraw 3D Interactive Renderer plug-in version 1.5

 RAVE.DLL - the optimized release build of QuickDraw 3D Accelleration library version 1.5

 3DViewer.DLL - the optimized release build of the 3D Viewer for Windows
        dependencies: QD3D.DLL, MSVCRT.DLL, RAVE.DLL, QD3D_IR2.q3x
 
The QuickDraw 3D Installer will put these libraries into your QuickDraw 3D directory (typically \Program Files\QuickDraw 3D).
QuickDraw 3D Viewer.exe 
- the optimized release build of the QuickDraw 3D Viewer application.
        dependencies: 3DViewer.DLL, QD3D.DLL, MSVCRT.DLL, RAVE.DLL, QD3D_IR2.q3x

In the Lib folder (the import libraries for QuickDraw 3D)
 QD3D.LIB - the import library for QD3D.DLL
 RAVE.LIB - the import library for RAVE.DLL 
 3DViewer.LIB - the import library for 3DViewer.DLL
 QD3D_D.LIB - the import library for QD3D_D.DLL
 RAVE_D.LIB - the import library for RAVE_D.DLL 
 3DViewer_D.LIB - the import library for 3DViewer_D.DLL

In the Interfaces folder
 The public interfaces for QD3D.DLL, Q3Viewer.DLL and RAVE.DLL. 

In the Sample folder
  Win32Sample - a simple application which demonstrates using the QuickDraw 3D core library to load and display 3D data on Windows. This sample demonstrates using the Win32 specific classes such as the Win32 DC Draw Context and Win32 Storage.

  ViewerSample - a test application which demonstrates using the QuickDraw 3D Viewer Controller API on Windows.

 ViewerSampleWin32Only - a test application which demonstrates using the QuickDraw 3D Viewer Controller using only the Win32 API. There are two variants of this program: one which is linked with 3DViewer.LIB and one which loads the 3DViewer.DLL dynamically at runtime. Note: 3DMF models may be opened by dropping them on the viewer window.

Documentation
The "Documentation" subdirectory of this release includes Adobe Acrobat PDF versions of the QuickDraw 3D reference "3D Graphics Programming With QuickDraw 3D and two introductory articles from Apple technical journal develop. Even though the develop articles discuss using QuickDraw 3D with the MacOS most of the material contained therein is equally applicable to the Win32 version of QuickDraw 3D. 

"3D Graphics Programming With QuickDraw 3D" is available from Addison-Wesley Publishing Company. ISBN 0-201-48926-0

QD3D.hlp - a WinHelp version of the QuickDraw 3D 1.0 for MacOS quick reference.

Win32 3DViewer ERS.rtf - preliminary documentation on the Win32 version of the 3D Viewer Controller.

Redistribution
For information on obtaining a license to redistribute QuickDraw 3D for Win32 or MacOS with your application contact Shawn Hopwood (hopwood@apple.com). 

The debug versions of the library may never be redistributed. Only the full installer may be redistributed under license from Apple Computer, Inc.

Feedback
Please send bug reports to scottk@apple.com. In the event that you have to report a problem please be sure to specify that you are using this 1.5.0 Win32 release and be sure to include a complete description of your PC system configuration including video board and video driver configuration.

Send your comments and feedback on this release to hopwood@apple.com. 

Apple Computer's 3D technologies evangelist, Shawn Hopwood (hopwood@apple.com) is eager to work with developers.  Contact Shawn with details of your product.

Thanks for choosing QuickDraw 3D, and good luck with your development efforts!!

The QuickDraw 3D team.